/**
 * 
 */
package com.pxingg.fep;

import com.pxingg.exception.XException;

/**
 * 一个对外通信端口的公共接口类，实现对外通信端口的公共方法<br>
 * 
 * @author pxingg.com
 *
 */
public interface CommPort
{
    /**
     * 当前可以读取的字节数
     * @return 当前可以读取的字节数
     * @throws XException
     */
    public int available() throws XException;

    /**
     * 关闭已经打开的通信端口<br>
     * 如果这个端口已经关闭，那么会直接返回
     * @throws XException
     */
    public void close()throws XException;

    /**
     * 把当前输出缓冲区的数据给发送出去
     * @return
     * @throws XException
     */
    public void flush() throws XException;

    /**
     * 获取当前通信端口的别名
     * @return 当前通信端口的别名
     */
    public String getAliasName();

    /**
     * 检测一个端口是否已经关闭
     * @return true: 端口已经关闭，或者已经失效<br>
     *         false: 端口成功打开，并且能够正常工作
     */
    public boolean isClose();

    /**
     * 检测一个端口是否已经打开
     * @return true: 端口已经成功打开，并且能够正常使用<br>
     *         false: 端口没有成功打开，或者目前已经失效
     */
    public boolean isOpen();

    /**
     * 打开一个通信端口
     * @return 一个成功打开的通信端口
     * @throws XException
     */
    public CommPort open() throws XException;

    /**
     * 读取一个字节的数据
     * @return 读取到的数据
     * @throws XException
     */
    public int read() throws XException;

    /**
     * 读取数据到一个字节数组中
     * @param data 保存数据的字节数组
     * @return 读取到的数据的长度
     * @throws XException
     */
    public int read(byte [] data) throws XException;

    /**
     * 读取数据并保存到一个字节数组的指定位置
     * @param data 保存数据的字节数组
     * @param start 保存数据的开始位置
     * @param length 最大的读取字节长度
     * @return 读取到的数据的长度
     * @throws XException
     */
    public int read(byte[] data, int start, int length) throws XException;

    /**
     * 如果当前通信端口已经打开，那么就先关闭当前通信端口，然后重新打开通信端口<br>
     * 如果当前通信端口没有打开或者已经失效，就直接打开这个通信端口
     * @return 一个成功打开的通信端口
     * @throws XException
     */
    public CommPort reopen() throws XException;

    /**
     * 发送一个字节数组的数据到系统外部
     * @param data 需要发送的数据
     * @return 当前使用的通信端口
     * @throws XException
     */
    public CommPort write(byte[] data) throws XException;

    /**
     * 发送一个字节数组的数据到系统外部
     * @param data 需要发送的数据
     * @param start 发送数据的起始位置
     * @param length 需要发送数据的长度
     * @return 当前使用的通信端口
     * @throws XException
     */
    public CommPort write(byte[] data, int start, int length) throws XException;

    /**
     * 发送一个字节的数据到系统外部
     * @param data 需要发送的数据
     * @return 当前使用的通信端口
     * @throws XException
     */
    public CommPort write(int data) throws XException;


}
